Skip to main content

Quickstart TideCloak App

This developer-oriented guide will take you through the minimal steps to set up a development environment with a fully-functional TideCloak server, and build your first very-own Client-Server NextJS web application, secured with TideCloak - all in 5 minutes.

Prerequisites​

Docker installed and running

Here's an example on how to set up Docker on Debian 12 linux environment:

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove -y $pkg; done



sudo apt-get update

sudo apt-get install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo tee /etc/apt/keyrings/docker.asc > /dev/null

sudo chmod a+r /etc/apt/keyrings/docker.asc



echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null



sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Node.js, curl and jq installed and updated

Here's an example on how to install Node NPM on Debian 12 linux environment (the app template needs Node.js 20.9 or later):

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

sudo apt-get install -y nodejs curl jq

sudo npm install -g npm@latest
Internet connectivity

Yeah... You'll have to sort it out yourself.

1. Start TideCloak in Dev Mode​

Run a pre‑configured Dev container:

sudo docker run \

  --name mytidecloak \

  -d \

  -v .:/opt/keycloak/data/h2 \

  -p 8080:8080 \

  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \

  -e KC_BOOTSTRAP_ADMIN_PASSWORD=password \

  tideorg/tidecloak-dev:latest
You don't need to worry about changing any of these settings

But if you want, here what those settings for:

  • --name: setting name for the server
  • -d: run in the background
  • -v: map the database to local folder to make it persistant
  • -p 8080:8080: map host port
  • KC_BOOTSTRAP_ADMIN_[USERNAME | PASSWORD]: set admin credentials

After few seconds, you'll be able to access the tide-console for your realm at http://localhost:8080/realms/{realm}/tide-console/.

Optional: Check TideCloak console logs​

sudo docker logs mytidecloak -f

2) Initialize the template project​

The initializer will automatically create the realm and clients on your TideCloak server. This includes the Tide IdP, license activation, first admin assignment and Quorum-Enforced Governance enablement.

Simply follow the instructions and use defaults if unsure.

npm init @tidecloak/nextjs@latest my-app

Complete Tide enrolment when the initializer asks​

After the prompts, the initializer creates the realm and generates the app, then stops and prints a line like this:

ACTION REQUIRED: Open this URL and complete Tide enrollment: https://...

That link sets up the Tide account for your realm's first admin. Open it, finish enrolment in the Tide enclave, and leave the initializer running. It polls for the new account and finishes on its own once enrolment lands. The enclave step can take a few minutes.

note

Until enrolment completes there is no first admin, so the realm is unfinished and the app has nothing working to start against.

3) Build and run the app​

cd my-app

npm install
npm run dev

4) Have a play 🎉​

Access your app on http://localhost:3000. You should see the Welcome! login page.

Done! You've just deployed a TideCloak Dev server, activated your license, created and assigned the main admin, built and deployed your first TideCloak-protected app - and all in 5 minutes.

You can find more information on this project's Github repo page.